home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / LANG / C / LIB / DESK / CORE / Desk / h_doc / MsgTrans < prev    next >
Text File  |  1996-07-05  |  14KB  |  437 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for 
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #                                      
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    MsgTrans.h
  12.     Author:  Copyright © 1994 Tony Houghton, 1996 Julian Smith
  13.     Version: 1.10 (12 Jun 1996)
  14.     Purpose: Interface to some of the most useful MessageTrans routines
  15.     History:
  16.         1.02 (05 Nov 1994) TH
  17.         1.10 (12 Jun 1996) JS    Added:
  18.                     Desk_MessageTrans_LookupGetSize
  19.                     Desk_MessageTrans_LookupIntoBuffer
  20.                         Desk_MessageTrans_LookupIntoBufferPos
  21.                         Desk_MessageTrans_LookupIntoBufferCat
  22.                         Desk_MessageTrans_OpenLookupCloseIntoBufferPos
  23.                         Desk_MessageTrans_OpenLookupCloseIntoBuffer
  24.                         Desk_MessageTrans_OpenLookupCloseIntoBufferCat
  25.             1.11 (05 Jul 1996) JS    Added
  26.                     Desk_MessageTrans_OpenFileRMA
  27.                     Desk_MessageTrans_CloseFileRMA
  28.  
  29.     NOTE: This is a veneer for the OS 'MsgTrans' system. An analogue of
  30.           this system is provided by the 'Msgs' sublibrary (Msgs.h).
  31.           Note that each system has advantages and disavantages compared
  32.           to the other...
  33. */
  34.  
  35. #ifndef __Desk_MsgTrans_h
  36. #define __Desk_MsgTrans_h
  37.  
  38. #ifdef __cplusplus
  39.     extern "C" {
  40. #endif
  41.  
  42.  
  43. #ifndef __Desk_DeskMem_h
  44.     #include "Desk.DeskMem.h"
  45. #endif
  46.  
  47.  
  48. /*K*************************************************************************
  49.  
  50. > MessageTrans
  51.  
  52. MessageTrans is Acorn's module for looking up messages in a text file; it
  53. is standard with RISC OS 3 onwards. You may prefer to use it to DeskLib's
  54. Msgs.h to avoid duplicating OS functionality or to gain access to system
  55. Messages files, because Msgs.h has an incompatible token format.
  56.  
  57. A Messages file has the following structure:
  58.  
  59.   # Comment lines begin with a #
  60.   Token:Text message with parameters %0 to %3
  61.   Token1
  62.   Token2/Token3:Message with more than one token
  63.   Percent:Message with a percent sign - %%
  64.  
  65. The final line must have a terminating LF.
  66.  
  67. PARAMETER SUBSTITUTION: Parameter substitution can be carried out by passing
  68.   up to 4 additional string parameters which are substituted for %0 to %3.
  69.  
  70. DEFAULT STRINGS: By supplying a token in the form "Token:Default string", if
  71.   the token is not matched in the file, the supplied string is used instead.
  72.  
  73. WILDCARDED/MULTIPLE TOKENS: A '?' in a token in the file matches any
  74.   character in the token supplied to be matched. A message can have more
  75.   than one token separated by '/' or LF.
  76.  
  77. DeskLib's MessageTrans library provides low level interfaces to the most
  78. essential of the module's SWIs. The others are unlikely to be useful in the
  79. context of a program written with DeskLib. In addition, there are some
  80. functions prefixed Desk_MsgTrans_ which provide higher level access to the calls.
  81.  
  82.  
  83. ****************************************************************************/
  84.  
  85.  
  86. /*K*************************************************************************
  87.  
  88. > MsgTrans
  89.  
  90. A group of functions providing higher level access to MessageTrans SWI
  91. functions. MsgTrans maintains a linked list of message files to allow it to find their
  92. buffers in memory for freeing.
  93.  
  94.  
  95. ****************************************************************************/
  96.  
  97.  
  98. typedef struct {
  99.   int data[4];
  100. } Desk_msgtrans_filedesc;
  101. /*
  102.   Purpose:  A file descriptor block for use with MessageTrans SWIs.
  103.   Fields:   Not available to user.
  104.   SeeAlso:  Desk_MessageTrans_OpenFile; Desk_MessageTrans_Lookup;
  105.             Desk_MessageTrans_CloseFile
  106. */
  107.  
  108.  
  109.  
  110. extern void    Desk_MessageTrans_FileInfo(char *filename, int *flags, int *size);
  111. /*
  112.   Purpose:  Get information about a Messages file prior to opening it
  113.   Inputs:   filename - Messages file path name
  114.   Outputs:  *flags   - bit 1 set indicates file is held in memory; all other
  115.                        bits are reserved
  116.             *size    - size of buffer necessary to hold file
  117.   Returns:  Pointer to an error block or NULL if successful
  118.   Errors:   -
  119.   SeeAlso:  Desk_MessageTrans_OpenFile
  120. */
  121.  
  122.  
  123.  
  124. extern void    Desk_MessageTrans_OpenFile(Desk_msgtrans_filedesc *filedesc,
  125.                                        char *filename, char *buffer);
  126. /*
  127.   Purpose:  Open or load a Messages file ready for reading
  128.   Inputs:   filedesc - Pointer to a file descriptor block which must be
  129.                          held in the RMA if buffer is NULL on entry
  130.             filename   - Messages file path name; string must be held in the
  131.                          RMA if buffer is NULL on entry
  132.             buffer     - Pointer to buffer to hold file or NULL; in the
  133.                          latter case the file will be used directly if
  134.                          possible, otherwise space will be allocated in the
  135.                          RMA.
  136.   Outputs:  -  
  137.   Returns:  Pointer to an error block or NULL if successful
  138.   Errors:   "Message file already open" if descriptor is in use
  139.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_CloseFile
  140. */
  141.  
  142.  
  143.  
  144. extern void    Desk_MessageTrans_Lookup(Desk_msgtrans_filedesc *filedesc, char *token,
  145.                                      char **buffer, int *size,
  146.                                      char *p0, char *p1, char *p2, char *p3);
  147. /*
  148.   Purpose:  Look up a token in an open Messages file and return its string
  149.   Inputs:   filedesc - pointer to a file descriptor block
  150.             token      - token to match
  151.             *buffer    - a pointer to the buffer to copy the string or NULL
  152.                          if the string is not to be copied
  153.             *size      - size of the buffer
  154.             p0 to p3   - optional parameters (NULL for no substitution)
  155.   Outputs:  *buffer    - now points to result string
  156.             *size      - updated to size of result before terminator
  157.   Returns:  Pointer to an error block or NULL if successful
  158.   Errors:   -
  159.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_OpenFile
  160. */
  161.  
  162.  
  163.  
  164. extern void    Desk_MessageTrans_CloseFile(Desk_msgtrans_filedesc *filedesc);
  165. /*
  166.   Purpose:  Close a Messages file
  167.   Inputs:   filedesc - Pointer to the file descriptor block
  168.   Outputs:  -  
  169.   Returns:  Pointer to an error block or NULL if successful
  170.   Errors:   -
  171.   SeeAlso:  Desk_mesgtrans_filedesc; Desk_MessageTrans_OpenFile
  172. */
  173.  
  174.  
  175.  
  176.  
  177.  
  178. extern void    Desk_MsgTrans_LoadFile(Desk_msgtrans_filedesc **filedesc, char *filename);
  179. /*
  180.   Purpose:  Allocate space for a Messages file and load it
  181.   Inputs:   filename  - path name of Messages file
  182.   Outputs:  *filedesc - points to file descriptor block
  183.   Returns:  An error if one of the SWIs fails or NULL
  184.   Errors:   As for Desk_MessageTrans_FileInfo and Desk_MessageTrans_OpenFile,
  185.             or 'NoStore' from Resources:Global.Messages
  186.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_FileInfo; Desk_MessageTrans_OpenFile;
  187.               MsgTrans
  188. */
  189.  
  190.  
  191.  
  192. #define Desk_MsgTrans_Lookup(filedesc, token, buffer, bufflen) \
  193.   Desk_MsgTrans_LookupPS((filedesc), (token), (buffer), (bufflen), \
  194.                     NULL, NULL, NULL, NULL)
  195. /*
  196.   MACRO:    extern Desk_os_error *Desk_MsgTrans_Lookup(Desk_msgtrans_filedesc *filedesc,
  197.                                              char *token,
  198.                                              char *buffer, int bufflen);
  199.  
  200.   Purpose:  Copy the matched token's string to a buffer and ensure it is NULL
  201.             terminated.
  202.   Inputs:   filedesc - descriptor or NULL for Global messages
  203.             token    - token to match
  204.             buffer   - where to store result
  205.             bufflen  - size of buffer available
  206.   Outputs:  *buffer - result string is copied here
  207.   Returns:  An error if Desk_MessageTrans_Lookup fails or NULL
  208.   Errors:   As for Desk_MessageTrans_Lookup
  209.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_Lookup; MsgTrans
  210. */
  211.  
  212.  
  213.  
  214. extern void    Desk_MsgTrans_LookupPS(Desk_msgtrans_filedesc *filedesc, char *token,
  215.                                    char *buffer, int bufflen,
  216.                                    char *p0, char *p1, char *p2, char *p3);
  217. /*
  218.   Purpose:  Desk_MsgTrans_Lookup with parameter substitution
  219.   Inputs:   filedesc - descriptor or NULL for Global messages
  220.             token    - token to match
  221.             buffer   - where to store result
  222.             bufflen  - size of buffer available
  223.             p0 to p3 - strings to substitute in result or NULL
  224.   Outputs:  *buffer - result string is copied here
  225.   Returns:  An error if Desk_MessageTrans_Lookup fails or NULL
  226.   Errors:   As for Desk_MessageTrans_Lookup
  227.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MessageTrans_Lookup; Desk_MsgTrans_Lookup; MsgTrans
  228. */
  229.  
  230.  
  231.  
  232. extern void    Desk_MsgTrans_LoseFile(Desk_msgtrans_filedesc *filedesc);
  233. /*
  234.   Purpose:  Closes a Messages file and frees memory used
  235.   Inputs:   block - pointer to Desk_msgtrans_block for file
  236.   Outputs:  -
  237.   Returns:  Pointer to an error block or NULL if successful
  238.   Errors:   As for Desk_MessageTrans_CloseFile
  239.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MsgTrans_LoadFile; Desk_MessageTrans_CloseFile;
  240.             MsgTrans
  241. */
  242.  
  243.  
  244.  
  245. #define Desk_MsgTrans_Report(filedesc, token, fatal) \
  246.   Desk_MsgTrans_ReportPS((filedesc), (token), (fatal), 0, 0, 0, 0)
  247. /*
  248.   MACRO:    extern Desk_os_error *Desk_MsgTrans_Report(Desk_msgtrans_filedesc *filedesc,
  249.                                              char *token, Desk_bool fatal);
  250.  
  251.   Purpose:  Looks up a message into an internal buffer and passes it to
  252.             Desk_Error_Report or Desk_Error_ReportFatal
  253.   Inputs:   filedesc - file descriptor
  254.             token    - token to match
  255.             fatal    - whether to call Desk_Error_Report or Desk_Error_ReportFatal
  256.   Outputs:  -
  257.   Returns:  Pointer to an error block or NULL if successful
  258.   Errors:   As for Desk_MessageTrans_Lookup
  259.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MsgTrans_Lookup; Desk_MsgTrans_ReportPS; MsgTrans;
  260.             Desk_Error_Report; Desk_Error_ReportFatal
  261. */
  262.  
  263.  
  264.  
  265. extern void    Desk_MsgTrans_ReportPS(Desk_msgtrans_filedesc *filedesc, char *token,
  266.                                    Desk_bool fatal,
  267.                                    char *p0, char *p1, char *p2, char *p3);
  268. /*
  269.   Purpose:  Looks up a message with parameter substitution into an
  270.             internal buffer and passes it to Desk_Error_Report or Desk_Error_ReportFatal
  271.   Inputs:   filedesc - file descriptor
  272.             token    - token to match
  273.             fatal    - whether to call Desk_Error_Report or Desk_Error_ReportFatal
  274.   Outputs:  -
  275.   Returns:  Pointer to an error block or NULL if successful
  276.   Errors:   As for Desk_MessageTrans_Lookup
  277.   SeeAlso:  Desk_msgtrans_filedesc; Desk_MsgTrans_LookupPS; Desk_MsgTrans_Report; MsgTrans;
  278.             Desk_Error_Report; Desk_Error_ReportFatal
  279. */
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286. int    Desk_MessageTrans_LookupGetSize( 
  287.         Desk_msgtrans_filedesc*    filedesc, 
  288.         const char*        token, 
  289.         const char*        p0, 
  290.         const char*        p1, 
  291.         const char*        p2, 
  292.         const char*        p3
  293.         );
  294. /*
  295. Returns the length of the string that would be generated when 'token' is
  296. expanded with p0-p3. This length excludes the terminating '\0'.
  297.  
  298. At the moment (12 Jun 1996), this works by trying temporary buffer sizes
  299. of 32,64, 128, ... until the returned text doesn't fill the buffer.
  300.  */
  301.  
  302.  
  303. void    Desk_MessageTrans_LookupIntoBuffer( 
  304.         Desk_deskmem_buffer*    buffer,
  305.         Desk_msgtrans_filedesc*    filedesc,
  306.         const char*        token,
  307.         const char*        p0,
  308.         const char*        p1,
  309.         const char*        p2,
  310.         const char*        p3
  311.         );
  312. /*
  313. Expands token into buffer, ensuring buffer is large enough.
  314.  */
  315.  
  316.  
  317. void    Desk_MessageTrans_LookupIntoBufferPos( 
  318.         Desk_deskmem_buffer*    buffer,
  319.         int            pos,
  320.         Desk_msgtrans_filedesc*    filedesc,
  321.         const char*        token,
  322.         const char*        p0,
  323.         const char*        p1,
  324.         const char*        p2,
  325.         const char*        p3
  326.         );
  327. /*
  328. Expands 'token' into 'buffer' starting at pos 'pos', after ensuring
  329. 'buffer' is large enough.
  330.  */
  331.  
  332.  
  333. void    Desk_MessageTrans_LookupIntoBufferCat( 
  334.         Desk_deskmem_buffer*    buffer,
  335.         Desk_msgtrans_filedesc*    filedesc,
  336.         const char*        token,
  337.         const char*        p0,
  338.         const char*        p1,
  339.         const char*        p2,
  340.         const char*        p3
  341.         );
  342. /*
  343. Appends expanded token to end of string in 'buffer'.
  344. */
  345.  
  346.  
  347. void    Desk_MessageTrans_OpenLookupCloseIntoBufferPos( 
  348.         Desk_deskmem_buffer*    buffer,
  349.         int            pos,
  350.         const char*        filename,
  351.         const char*        token,
  352.         const char*        p0,
  353.         const char*        p1,
  354.         const char*        p2,
  355.         const char*        p3
  356.         );
  357. /*
  358. As Desk_MessageTrans_LookupIntoBufferPos, except that the messages file
  359. is opened, the lookup performed, and then closed again.
  360.  */
  361.  
  362.  
  363. void    Desk_MessageTrans_OpenLookupCloseIntoBuffer( 
  364.         Desk_deskmem_buffer*    buffer,
  365.         const char*        filename,
  366.         const char*        token,
  367.         const char*        p0,
  368.         const char*        p1,
  369.         const char*        p2,
  370.         const char*        p3
  371.         );
  372. /*
  373. As Desk_MessageTrans_LookupIntoBuffer, except that the messages file
  374. is opened, the lookup performed, and then closed again.
  375.  */
  376.  
  377.  
  378.  
  379.  
  380. void    Desk_MessageTrans_OpenLookupCloseIntoBufferCat( 
  381.         Desk_deskmem_buffer*    buffer,
  382.         const char*        filename,
  383.         const char*        token,
  384.         const char*        p0,
  385.         const char*        p1,
  386.         const char*        p2,
  387.         const char*        p3
  388.         );
  389. /*
  390. As Desk_MessageTrans_LookupIntoBufferCat, except that the messages file
  391. is opened, the lookup performed, and then closed again.
  392.  */
  393.  
  394.  
  395.  
  396. typedef struct    {
  397.     char*            filename;
  398.     Desk_msgtrans_filedesc*    desc;
  399.     }
  400.     Desk_msgtrans_rmafiledesc;
  401. /*
  402. Used with Desk_MessageTrans_OpenFileRMA and
  403. Desk_MessageTrans_CloseFileRMA.
  404.  
  405. For safety, you should initialise a Desk_msgtrans_rmafiledesc to NULLs
  406. before use. Eg:
  407.  
  408. Desk_msgtrans_rmafiledesc    messages = { NULL, NULL};
  409.  */
  410.  
  411.  
  412. void    Desk_MessageTrans_OpenFileRMA( Desk_msgtrans_rmafiledesc* filedesc, const char* filename);
  413. /*
  414. Opens a message file, instructing MessageTrans to buffer the file
  415. automatically in the RMA. For such use, MessageTrans requires that the
  416. Desk_msgtrans_filedesc and filename are stored in the RMA (see PRMs
  417. 3-743), so 'filename' is copied into a block of RMA, and a
  418. 'Desk_msgtrans_filedesc' is also allocated in the RMA.
  419.  
  420. To use message file, call Desk_MessageTrans_Lookup etc with
  421. 'filedesc->desc'.
  422.  */
  423.  
  424. void    Desk_MessageTrans_CloseFileRMA( Desk_msgtrans_rmafiledesc* filedesc);
  425. /*
  426. Closes and frees all RMA memory associated with 'filedesc'.
  427.  */
  428.  
  429.  
  430.  
  431. #ifdef __cplusplus
  432. }
  433. #endif
  434.  
  435.  
  436. #endif
  437.